<div class="doc-content">



<header class="api-profile-header" >
  <h2 class="md-display-1" >{{currentDoc.name}} API Documentation</h2>
  
</header>



<div layout="row" class="api-options-bar with-icon"></div>


<div class="api-profile-description">
  <p>Displays a select box, bound to an ng-model.</p>
<p>When the select is required and uses a floating label, then the label will automatically contain
an asterisk (<code>*</code>). This behavior can be disabled by using the <code>md-no-asterisk</code> attribute.</p>
<p>By default, the select will display with an underline to match other form elements. This can be
disabled by applying the <code>md-no-underline</code> CSS class.</p>
<h3 id="option-params">Option Params</h3>
<p>When applied, <code>md-option-empty</code> will mark the option as &quot;empty&quot; allowing the option to  clear the
select and put it back in it&#39;s default state. You may supply this attribute on any option you
wish, however, it is automatically applied to an option whose <code>value</code> or <code>ng-value</code> are not
defined.</p>
<p><strong>Automatically Applied</strong></p>
<ul>
<li><code>&lt;md-option&gt;</code></li>
<li><code>&lt;md-option value&gt;</code></li>
<li><code>&lt;md-option value=&quot;&quot;&gt;</code></li>
<li><code>&lt;md-option ng-value&gt;</code></li>
<li><code>&lt;md-option ng-value=&quot;&quot;&gt;</code></li>
</ul>
<p><strong>NOT Automatically Applied</strong></p>
<ul>
<li><code>&lt;md-option ng-value=&quot;1&quot;&gt;</code></li>
<li><code>&lt;md-option ng-value=&quot;&#39;&#39;&quot;&gt;</code></li>
<li><code>&lt;md-option ng-value=&quot;undefined&quot;&gt;</code></li>
<li><code>&lt;md-option value=&quot;undefined&quot;&gt;</code> (this evaluates to the string <code>&quot;undefined&quot;</code>)</li>
<li><code ng-non-bindable>&lt;md-option ng-value=&quot;{{someValueThatMightBeUndefined}}&quot;&gt;</code></li>
</ul>
<p><strong>Note:</strong> A value of <code>undefined</code> <strong><em>is considered a valid value</em></strong> (and does not auto-apply this
attribute) since you may wish this to be your &quot;Not Available&quot; or &quot;None&quot; option.</p>
<p><strong>Note:</strong> Using the <code>value</code> attribute (as opposed to <code>ng-value</code>) always evaluates to a string, so
<code>value=&quot;null&quot;</code> will require the test <code>ng-if=&quot;myValue != &#39;null&#39;&quot;</code> rather than <code>ng-if=&quot;!myValue&quot;</code>.</p>

</div>


<div>
  

  

  
  <section class="api-section">
    <h2 id="Usage">Usage</h2>
  
    <p>With a placeholder (label and aria-label are added dynamically)</p>
<hljs lang="html">
  <md-input-container>
    <md-select
      ng-model="someModel"
      placeholder="Select a state">
      <md-option ng-value="opt" ng-repeat="opt in neighborhoods2">{{ opt }}</md-option>
    </md-select>
  </md-input-container>
</hljs>

<p>With an explicit label</p>
<hljs lang="html">
  <md-input-container>
    <label>State</label>
    <md-select
      ng-model="someModel">
      <md-option ng-value="opt" ng-repeat="opt in neighborhoods2">{{ opt }}</md-option>
    </md-select>
  </md-input-container>
</hljs>

<p>With a select-header</p>
<p>When a developer needs to put more than just a text label in the
md-select-menu, they should use the md-select-header.
The user can put custom HTML inside of the header and style it to their liking.
One common use case of this would be a sticky search bar.</p>
<p>When using the md-select-header the labels that would previously be added to the
OptGroupDirective are ignored.</p>
<hljs lang="html">
  <md-input-container>
    <md-select ng-model="someModel">
      <md-select-header>
        <span> Neighborhoods - </span>
      </md-select-header>
      <md-option ng-value="opt" ng-repeat="opt in neighborhoods2">{{ opt }}</md-option>
    </md-select>
  </md-input-container>
</hljs>

<h2 id="selects-and-object-equality">Selects and object equality</h2>
<p>When using a <code>md-select</code> to pick from a list of objects, it is important to realize how javascript handles
equality. Consider the following example:</p>
<hljs lang="js">
angular.controller(&#39;MyCtrl&#39;, function($scope) {
  $scope.users = [
    { id: 1, name: &#39;Bob&#39; },
    { id: 2, name: &#39;Alice&#39; },
    { id: 3, name: &#39;Steve&#39; }
  ];
  $scope.selectedUser = { id: 1, name: &#39;Bob&#39; };
});
</hljs>
<hljs lang="html">
<div ng-controller="MyCtrl">
  <md-select ng-model="selectedUser">
    <md-option ng-value="user" ng-repeat="user in users">{{ user.name }}</md-option>
  </md-select>
</div>
</hljs>

<p>At first one might expect that the select should be populated with &quot;Bob&quot; as the selected user. However,
this is not true. To determine whether something is selected,
<code>ngModelController</code> is looking at whether <code>$scope.selectedUser == (any user in $scope.users);</code>;</p>
<p>Javascript&#39;s <code>==</code> operator does not check for deep equality (ie. that all properties
on the object are the same), but instead whether the objects are <em>the same object in memory</em>.
In this case, we have two instances of identical objects, but they exist in memory as unique
entities. Because of this, the select will have no value populated for a selected user.</p>
<p>To get around this, <code>ngModelController</code> provides a <code>track by</code> option that allows us to specify a different
expression which will be used for the equality operator. As such, we can update our <code>html</code> to
make use of this by specifying the <code>ng-model-options=&quot;{trackBy: &#39;$value.id&#39;}&quot;</code> on the <code>md-select</code>
element. This converts our equality expression to be
<code>$scope.selectedUser.id == (any id in $scope.users.map(function(u) { return u.id; }));</code>
which results in Bob being selected as desired.</p>
<p>Working HTML:</p>
<hljs lang="html">
<div ng-controller="MyCtrl">
  <md-select ng-model="selectedUser" ng-model-options="{trackBy: '$value.id'}">
    <md-option ng-value="user" ng-repeat="user in users">{{ user.name }}</md-option>
  </md-select>
</div>
</hljs>
  
  </section>
  
  <div class="api-param-section">
    <h2>
      
        Attributes
      
    </h2>
    <div class="api-param-table">
      
<table class="md-api-table">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
  
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          <b>* ng-model</b>
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-expression">expression</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-expression">expression</code></td>
        <td class="description">
          <p>The model!</p>

          
        </td>
      </tr>
    
  
    
  
    
  
    
  
    
  
    
  
    
  
    
  
    
  
  
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          multiple
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-boolean">boolean</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-boolean">boolean</code></td>
        <td class="description">
          <p>Whether it&#39;s multiple.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          md-on-close
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-expression">expression</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-expression">expression</code></td>
        <td class="description">
          <p>Expression to be evaluated when the select is closed.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          md-on-open
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-expression">expression</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-expression">expression</code></td>
        <td class="description">
          <p>Expression to be evaluated when opening the select.
Will hide the select options and show a spinner until the evaluated promise resolves.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          md-selected-text
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-expression">expression</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-expression">expression</code></td>
        <td class="description">
          <p>Expression to be evaluated that will return a string
to be displayed as a placeholder in the select input box when it is closed.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          placeholder
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-string">string</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-string">string</code></td>
        <td class="description">
          <p>Placeholder hint text.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          md-no-asterisk
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-boolean">boolean</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-boolean">boolean</code></td>
        <td class="description">
          <p>When set to true, an asterisk will not be appended to the
floating label. <strong>Note:</strong> This attribute is only evaluated once; it is not watched.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          aria-label
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-string">string</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-string">string</code></td>
        <td class="description">
          <p>Optional label for accessibility. Only necessary if no placeholder or
explicit label is present.</p>

          
        </td>
      </tr>
    
  
    
      <tr class="api-params-item">
        <td style="white-space: nowrap;">
          md-container-class
          
          <span hide show-sm>
<code class="api-type label type-hint type-hint-string">string</code></span>
        </td>
        <td style="white-space: nowrap;">
<code class="api-type label type-hint type-hint-string">string</code></td>
        <td class="description">
          <p>Class list to get applied to the <code>.md-select-menu-container</code>
element (for custom styling).</p>

          
        </td>
      </tr>
    
  

  </tbody>
</table>

    </div>
  </div>
  


  
</div>


</div>
